Itential Docs & Guides | Drive Automation for Modern Networks

Itential Automation Gateway allows users to automate the administration of their network by providing a collection of Ansible roles that perform device monitoring and configuration tasks on supported device types. The roles are designed to utilize advanced features of the command and configuration networking modules that are developed, tested, and maintained by the Ansible open-source community. Devices are managed by running CLI and NETCONF commands over the SSH protocol. The parameters required for device connectivity are made available through the Automation Gateway inventory management subsystem.

The following roles are distributed with Automation Gateway.

Role	Description
`itential_cli`	Execute CLI commands on a network device.
`itential_get_info`	Retrieve the device serial number, OS version, and MAC addresses for all network interfaces.
`itential_get_health`	Retrieve CPU and memory statistics for a device.
`itential_get_config`	Retrieve the current running configuration for a device.
`itential_set_config`	Add, modify, and delete specific configuration sections and lines on a device.
`itential_restore_config`	Replace the current running configuration of a device with a completely new version.

Execution Flow By Role Type

Depending on the inventory variables present, the above roles will defer to one of three flows: fully supported, semi-supported, and custom/unsupported.

Fully Supported (Ansible-based)

The Ansible-based roles are for use with our explicit list of fully supported devices located in our support documentation. This list includes devices such as, but not limited to: Arista EOS, Alcatel SROS, Aruba CX, Cisco ASA/IOS/Nexus/IOS-XR, F5 Bigip, Junos JunOS. Support documentation can be found at IAP Compatibility.

Executing a role against a fully supported device enables users to utilize the full suite of Automation Gateway and Automation Platform features, such as these roles, Configuration Manager, Golden Configuration, and Command Templates.

Requirements

The device is explicitly in Itential's list of supported devices, and you can successfully connect to the device via Ansible's connection parameters.

Important Variables

The ansible_network_os variable must match a valid Ansible OS type, and it must be in the list of devices supported by Itential, such as ios for Cisco IOS.

Example Host

{
  "name": "Example_IOS",
  "ansible_host": "ios.example.com",
  "ansible_connection": "network_cli",
  "ansible_network_os": "ios",
  "ansible_username": "username",
  "ansible_password": "password",
  "ansible_become": true,
  "ansible_become_password": "password"
}

Semi-Supported (Netmiko-based)

The Netmiko-based roles are for use with devices that do not fall under the fully supported category, but which have prebuilt support from the Netmiko library. This list is much greater than the fully supported list, however it has its own caveats and levels of support from that library. See Netmiko Platforms for additional information regarding the device_type variable and options.

Executing a role against a semi-supported device enables users to utilize the majority of Automation Gateway and Automation Platform features, such as these roles and Configuration Manager/Golden Configuration. However, it does not come with any guarantee that Netmiko can successfully connect to the device, or operate against the device exactly as a user may expect. Instead, it provides a reasonable expectation that if Netmiko has a device_type for your device, you can easily enable connectivity and test the available functionality (such as sending commands, updating configuration).

Requirements

The device is not in Itential's list of supported devices, and you can successfully connect to the device via Netmiko's connection parameters. You are willing to accept that a certain amount of research and customization is required to enable connectivity and functionality, but that once enabled, it will work with the majority of Automation Gateway and Automation Platform features.

The Itential Netmiko roles can be executed through the main itential_* roles or directly via the itential_netmiko_* roles.

Important Variables

The ansible_network_os variable must not match the name of a fully supported device and should generally be omitted to avoid confusion and ensure the correct execution path is followed.
A local connection type is required; therefore ansible_connection must be set to local.
Either provider.device_type or netmiko_device_type must be a valid netmiko device_type.

Example Host (Explicit Usage)

The following example host shows an explicit set of Netmiko-related variables nested under the provider object so that it is very clear that this host is meant to be used only with the Netmiko roles.

{
    "name": "Example_IOS",
    "variables": {

        "**********REQUIRED VARIABLES**********": "",

        "ansible_connection": "local",
        "provider": {
            "host": "ios.example.com",
            "device_type": "cisco_ios",
            "username": "username",
            "password": "password"
        },

        "**********END REQUIRED VARIABLES**********": "",


        "**********OPTIONAL VARIABLES**********": "",

        "ansible_host": "ios.example.com",
        "ansible_port": 22,
        "ansible_network_os": "cisco_ios",
        "end_command": "end",
        "save_command": "commit apply",
        "get_config_command": "show run",
        "get_state_command": "show version",

        "**********END OPTIONAL VARIABLES**********": ""
    }
}

Example Host (Implicit Usage)

The following example host shows an implicit set of Netmiko-related variables which are declared outside of the provider object. This method allows the user to use mostly Ansible variables, which are converted into the provider object in the background, with the addition of netmiko_device_type so that it is correctly routed to the Netmiko roles.

{
    "name": "Example_IOS",
    "variables": {

      "**********REQUIRED VARIABLES**********": "",

      "ansible_connection": "local",
      "ansible_host": "ios.example.com",
      "ansible_user": "username",
      "ansible_password": "password",
      "netmiko_device_type": "cisco_ios",

      "**********END REQUIRED VARIABLES**********": "",


      "**********OPTIONAL VARIABLES**********": "",

      "ansible_port": 22,
      "ansible_network_os": "cisco_ios",
      "end_command": "end",
      "save_command": "commit apply",
      "get_config_command": "show run",
      "get_state_command": "show version",

      "**********END OPTIONAL VARIABLES**********": ""
  }
}

Unsupported (Custom)

The unsupported, custom role types are only for use with devices that do not fall under the fully supported list and cannot be configured to work with Netmiko via the semi-supported role type. This execution method requires that the user copy a role template and create their own Ansible role, modules, etc to enable connectivity and functionality with their unsupported device.

Executing a role against an unsupported device comes with no expectation that the device will be able to utilize the full suite of Automation Gateway and Automation Platform features, such as these roles, Configuration Manager, Golden Configuration and Command Templates.

Requirements

The device in question cannot be executed against the fully supported or semi-supported roles.
The ansible_network_os variable must not be in the list of supported device types and should instead be a made-up value that matches the custom role you created (see the templates for additional information).

Example Host

{
  "name": "Example_IOS",
  "ansible_host": "ios.example.com",
  "ansible_connection": "???",
  "ansible_network_os": "custom_unsupported_ios",
  "...any other custom variables for your custom role...": "..."
}

Role Execution Parameters

Automation Gateway clients execute roles on a device using the REST /roles/{role_name}/execute route. The role execution input parameter is a JSON object that contains an array of host strings and an args object that includes a set of key/value pairs that are specific to the role itself. A JSON schema that describes each role's argument parameters is available via the /roles/{role_name} route. Detailed documentation on role endpoints can be found in the API Documentation section of the Automation Gateway UI.

Below is a sample role input parameter for the itential_set_config role.

Sample Role Request Object

{
  "hosts":["eos_host"],
  "args":
  {  
    "transactions": [
      {
        "action": "add",
        "parents": ["interface Management 1"],
        "config_line": "ip address 10.1.2.3/24",
        "id": "anyIDString"
      }
    ]
  },
  "strict_args": true
}

An Ansible role consists of a number of tasks, each of which produces its own results object.

Automation Gateway collects the task results objects and returns them as an array in the order in which they were executed.

Task Key Naming Convention

The Itential Ansible roles include a task results object with a task key whose value always takes the form of the "Task key naming convention" shown below:

{role} response

Where {role} is replaced with the name of the role executed.

Example: itential_set_config response

The results object from that response task contains the response data from the role for the device.

All other task results can be ignored and are available for informational and debugging purposes only.

Note that the format of the data contained within the results object will vary per role.

In addition, a status key indicates whether the task succeeded (SUCCESS), or failed (FAILURE).

Roles that contain multiple requests will have multiple response objects, each with their own status and results keys.

Sample Role Response

[
    {
        "role": "itential_set_config",
        "task": "execute config module on eos platform",
        "host": "eos_host",
        "status": "SUCCESS",
        "argument_warnings": null,
        "results": {
            "commands": [
                "interface Management 1",
                "ip address 10.0.5.17/24"
            ],
            "changed": true,
            "session": "ansible_1548718829",
            "updates": [
                "interface Management 1",
                "ip address 10.0.5.17/24"
            ],
            "diff": {
                "prepared": "--- system:/running-config\n+++ session:/ansible_1548718829-session-config\n@@ -27,6 +27,7 @@\n
    ip address 192.168.32.20/24\n !\n interface Management1\n+   ip address 10.0.5.17/24\n !\n ip route 0.0.0.0/0 10.0.2.2\n !"
            }
        }
    },
    {
        "role": "itential_set_config",
        "task": "itential_set_config response",
        "host": "eos_host",
        "status": "SUCCESS",
        "argument_warnings": null,
        "results": {
            "config_request": {
                "action": "add",
                "config_line": "ip address 10.0.5.17/24",
                "parents": [
                    "interface Management 1"
                ],
                "id": "anyIDString"
            },
            "config_response": {
                "failed": false,
                "changed": true,
                "id": "anyIDString"
            },
            "changed": false
        }
    }
]

Role Examples

Referenced below are several Automation Gateway roles, including examples of request and response objects.

`itential_cli`

Description: Execute CLI commands on a network device. This role also provides support for handling commands that are required to respond to a prompt in order to complete the command.

Note: As of 2019.3, this role does not support handling command prompts for F5 (BigIP) devices or Junos devices that are configured with the ansible_connection variable set to netconf.

Sample Request Object

{
  "hosts": [
    "ios_aws"
  ],
  "args": {"command": ["show clock"]}
}

Sample Response Object

[
    {
        "role": "itential_cli",
        "task": "itential_cli response",
        "host": "ios_host",
        "status": "SUCCESS",
        "argument_warnings": null,
        "results": {
            "stdout_lines": [
                [
                    "*08:45:04.200 UTC Fri Nov 8 2019"
                ]
            ],
            "stdout": [
                "*08:45:04.200 UTC Fri Nov 8 2019"
            ],
            "changed": false
        }
    }
]

Sample Request Object for Command Prompts

{
  "hosts": [
    "ios_aws"
  ],
  "args":{"command": [{"command": "clear counters GigabitEthernet2", "prompt": ["confirm"], "answer": ["y"]}]}
}

Sample Response Object for Command Prompts

[
    {
        "role": "itential_cli",
        "task": "itential_cli response",
        "host": "ios_aws",
        "status": "SUCCESS",
        "argument_warnings": null,
        "results": {
            "stdout_lines": [
                [
                    "Clear \"show interface\" counters on this interface [confirm]y"
                ]
            ],
            "stdout": [
                "Clear \"show interface\" counters on this interface [confirm]y"
            ],
            "changed": false
        }
    }
]

`itential_get_info`

Description: Retrieve information about a device including OS type, serial number, and the MAC address for all network interfaces.

Sample Request Object

{
  "hosts": [
    "ios_aws"
  ],
  "args": {}
}

Sample Response Object

{
        "role": "itential_get_info",
        "task": "itential_get_info response",
        "host": "ios_aws",
        "status": "SUCCESS",
        "argument_warnings": null,
        "results": {
            "serial_number": "9IKZMWL4K0X",
            "raw_ansible_facts": {
                "ansible_net_serialnum": "9IKZMWL4K0X",
                "ansible_net_all_ipv4_addresses": [
                    "10.11.0.72"
                ],
                "ansible_net_model": "CSR1000V",
                "ansible_net_hostname": "ph10894c",
                "ansible_net_gather_subset": [
                    "hardware",
                    "default",
                    "interfaces"
                ],
                "ansible_net_interfaces": {
                    "GigabitEthernet1.1": {
                        "macaddress": "0e4e.fc45.d044",
                        "lineprotocol": "down ",
                        "description": null,
                        "duplex": null,
                        "mediatype": null,
                        "mtu": 1500,
                        "operstatus": "deleted",
                        "bandwidth": 1000000,
                        "ipv4": [],
                        "type": "CSR vNIC"
                    },
                    "GigabitEthernet1": {
                        "macaddress": "0e4e.fc45.d044",
                        "lineprotocol": "up ",
                        "description": null,
                        "duplex": "Full",
                        "mediatype": "RJ45",
                        "mtu": 1500,
                        "operstatus": "up",
                        "bandwidth": 1000000,
                        "ipv4": [
                            {
                                "subnet": "24",
                                "address": "10.11.0.72"
                            }
                        ],
                        "type": "CSR vNIC"
                    }
                },
                "ansible_net_version": "03.16.02.S",
                "ansible_net_all_ipv6_addresses": [],
                "ansible_net_memtotal_mb": 1672835,
                "ansible_net_filesystems": [
                    "bootflash:"
                ],
                "ansible_net_image": "bootflash:packages.conf",
                "ansible_net_memfree_mb": 1442035
            },
            "interfaces": {
                "GigabitEthernet1.1": {
                    "macaddress": "0e4e.fc45.d044",
                    "lineprotocol": "down ",
                    "description": null,
                    "duplex": null,
                    "mediatype": null,
                    "mtu": 1500,
                    "operstatus": "deleted",
                    "bandwidth": 1000000,
                    "ipv4": [],
                    "type": "CSR vNIC"
                },
                "GigabitEthernet1": {
                    "macaddress": "0e4e.fc45.d044",
                    "lineprotocol": "up ",
                    "description": null,
                    "duplex": "Full",
                    "mediatype": "RJ45",
                    "mtu": 1500,
                    "operstatus": "up",
                    "bandwidth": 1000000,
                    "ipv4": [
                        {
                            "subnet": "24",
                            "address": "10.11.0.72"
                        }
                    ],
                    "type": "CSR vNIC"
                }
            },
            "os_version": "03.16.02.S",
            "changed": false
        }
    }

`itential_get_health`

Description: Retrieve CPU and memory statistics for a device. The itential_get_health response task returns a memory usage statistics object and an array of CPU usage objects.

The memory object contains the total memory and free memory values in megabytes. Each object in the cpu_stats array reflects a sample period during which the CPU usage was measured.

The number of objects in the array is based on what sample periods are available from each device. Note that some network devices track CPU utilization as a percentage, while others use the concept of load average.

The following keys are contained in each CPU usage object.

Key	Description
`value`	CPU utilization (percentage) or load average.
`type`	Utilization or loading.
`period`	Sample space (in seconds) in which the value was calculated.

Sample Request Object

{
  "hosts": [
    "ios_aws"
  ],
  "args": {}
}

Sample Response Object

[
   {
        "role": "itential_get_health",
        "task": "itential_get_health response",
        "host": "ios_aws",
        "status": "SUCCESS",
        "argument_warnings": null,
        "results": {
           "memory": {
                "memtotal_mb": 814,
                "memfree_mb": 556
           },
           "cpu_stats": [
                { "value": 15, "type": "utilization", "period": 5 },
        { "value": 20, "type": "utilization", "period": 60 },
        { "value": 32, "type": "utilization", "period": 300 }
           ],
           "changed": false
        }
   },
   {
        "role": "itential_get_health",
        "task": "itential_get_health response",
        "host": "eos_host",
        "status": "SUCCESS",
        "argument_warnings": null,
        "results": {
           "memory": {
                "memtotal_mb": 1970,
                "memfree_mb": 1120
           },
           "cpu_stats": [
                { "value": 0.8, "type": "loadavg", "period": 60 },
        { "value": 0.2, "type": "loadavg", "period": 300 },
        { "value": 0.2, "type": "loadavg", "period": 900 }
           ],
           "changed": false
        }
   },
]

`itential_get_config`

Description: Retrieve the current running configuration from a device. The results returned in the config_data field can be directly passed as a value to the config_file parameter of the itential_restore_config role.

Sample Request Object

{
  "hosts": [
    "ios_host"
  ],
  "args": {}
}

Sample Response Object

{
        "role": "itential_get_config",
        "task": "itential_get_config response",
        "host": "ios_host",
        "status": "SUCCESS",
        "argument_warnings": null,
        "results": {
            "config_data": "! Last configuration change at 01:11:48 UTC Thu Feb 7 2019 by admin\n!\nversion 15.4\n
service timestamps debug datetime msec\nservice timestamps log datetime msec\nno platform punt-keepalive disable-kernel-core\n
platform console virtual\n!\nhostname roland-router\n!\nboot-start-marker\nboot-end-marker\n!\n!\n
enable secret 5 $1$.U3b$Uoy64G6eZ4qXzCbihv9rd0\nenable password admin\n!\naaa new-model\n!\n!\naaa authentication login default local\n
aaa authorization exec default local none \n!\n!\n!\n!\n!\naaa session-id common\n!\n!\n!\n!\n!\n!\n!\n\n\n
ip domain name test.example.com\n!\n!\n!\n!\n!\n!\n!\n!\n!\n!\nsubscriber templating\nmultilink bundle-name authenticated\n
!\n!\nlicense udi pid CSR1000V sn 9V86NBL1EE6\n!\nusername admin privilege 15 password 0 admin\n!\nredundancy\n mode none\n
!\n!\n!\nip ssh time-out 60\nip ssh authentication-retries 2\nip ssh version 2\nip ssh pubkey-chain\n  username admin\n
   key-hash ssh-rsa 3141D7C2ECA54D3611445D83564F8391 roland.provencher@itential.comendend\nip scp server enable\n
!\n!\n!\n!\ninterface GigabitEthernet1\n ip address 10.0.2.15 255.255.255.0\n negotiation auto\n!\ninterface GigabitEthernet2\n
 ip address 192.168.32.40 255.255.255.0\n negotiation auto\n!\n!\nvirtual-service csr_mgmt\n!\nip forward-protocol nd\n!\n
no ip http server\nno ip http secure-server\n!\n!\nsnmp-server community redhat RO\nsnmp-server community REDSOX RO\n
snmp-server community PATS RO\n!\n!\n!\n!\ncontrol-plane\n!\n!\nline con 0\n stopbits 1\nline aux 0\n stopbits 1\n
line vty 0 4\n privilege level 15\n password admin\n login authentication local\n transport input ssh\n!\n!\nend",
            "changed": false,
            "_ansible_delegated_vars": {
                "ansible_delegated_host": "localhost",
                "ansible_host": "localhost"
            }
        }
}

`itential_set_config`

Description: Add, modify, and delete specific configuration sections and lines on a device. The itential_set_config role takes an array of transactions as an argument.

Each transaction is an object representing a single configuration line that will be applied to the device configuration in the order they appear in the array.

Each transaction will be treated individually and produce its own status and results. A failure on one transaction will not stop the next transaction from being attempted.

A transaction object consists of the following fields.

Field	Description
`action`	Configuration action to perform on a device. Possible values are `add`, `modify`, and `delete`.
`parents`	The ordered set of parents that uniquely identify the section or hierarchy the configuration line should be applied against. If the parents argument is empty, the configuration line is applied against the root of the configuration tree.
`config_line`	The configuration line being acted upon by the device. The line must match the native device configuration syntax.
`id`	Optional. String parameter that can be used to match a transaction request with the corresponding device configuration response. The `id` string will be return as a key in the `config_response` results object of the role.

Sample Request Object

{"hosts":["eos_host"],
 "args":{"transactions": [{"action": "add", "parents": ["interface Management 1"], "config_line": "ip address 10.0.5.17/24", "id": "first"},
                          {"action": "modify", "parents": ["interface Management 1"], "config_line": "ip address 10.0.5.27/24", "id": "second" },
                          {"action": "delete", "parents": [""], "config_line": "ip address 10.0.5.27/24", "id": "third"}] }, "strict_args": true }

Sample Response Object

{
        "role": "itential_set_config",
        "task": "itential_set_config response",
        "host": "eos_host",
        "status": "SUCCESS",
        "argument_warnings": null,
        "results": {
            "config_request": {
                "action": "add",
                "config_line": "ip address 10.0.5.17/24",
                "parents": [
                    "interface Management 1"
                ],
                "id": "first"
            },
            "config_response": {
                "failed": false,
                "id": "first"
            },
            "changed": false
        }
    },
    {
        "role": "itential_set_config",
        "task": "itential_set_config response",
        "host": "eos_host",
        "status": "SUCCESS",
        "argument_warnings": null,
        "results": {
            "config_request": {
                "action": "modify",
                "config_line": "ip address 10.0.5.27/24",
                "parents": [
                    "interface Management 1"
                ],
                "id": "second"
            },
            "config_response": {
                "failed": false,
                "id": "second"
            },
            "changed": false
        }
    },
    {
        "role": "itential_set_config",
        "task": "itential_set_config response",
        "host": "eos_host",
        "status": "FAILURE",
        "argument_warnings": null,
        "results": {
            "msg": "Configuration request failed",
            "config_request": {
                "action": "delete",
                "config_line": "ip address 10.0.5.27/24",
                "parents": [
                    ""
                ],
                "id": "third"
            },
            "config_response": {
                "msg": "Error on executing commands ['', 'no ip address 10.0.5.27/24']",
                "failed": true,
                "data": "no ip address 10.0.5.27/24\r\n% Invalid input\r\nlocalhost(config-s-ansibl)#",
                "id": "third"
            },
            "changed": false
        }
    }
]

`itential_restore_config`

Description: Replace the current running configuration of a device with a completely new version.

The itential_restore_config_role takes the argument config_file, which is a string buffer containing the device configuration file in its native format.

The itential_get_config role returns the device configuration file in its native format in the key config_data.

The results from that role can be a starting point for configuration modifications or be used "as is" for the argument value in the config_file.

SCP Requirements for IOS (Cisco) and EOS (Arista) Device Types

To execute the restore operation, Cisco IOS and Arista EOS devices require the new configuration file to be present on the system. The itential_restore_config role accomplishes this by using the Ansible scp module to transfer the new configuration file to the device. Below are instructions for SCP and SSH key configuration requirements when using the itential_restore_config role on IOS and EOS devices.

SCP must be enabled using the the following configuration mode command (IOS): # ip scp server enable
For the user account in the device inventory variable ansible_user, SSH keys must be set-up between Automation Gateway and the IOS/EOS device so that a password in not required for device login. Otherwise, the SCP module will timeout and the role will fail.
The inventory variable ansible_ssh_private_key_file must be present for the device and set to the path of the private key file that was created in the previous step.

Sample Request Object

{"hosts":["junos_host"],
 "args":{"config_file": "## Last changed: 2019-01-11 06:31:03 UTC\nversion 12.1R1.9;\ngroups {\n    global;\n}\napply-groups global;\nsystem {\n    root-authentication {\n
        encrypted-password \"$1$Fmd79e7l$0biZFh9lhSt1qb/E06HoL.\";\n    }\n    services {\n        ftp;\n        ssh;\n        netconf {\n            ssh;\n        }\n
    }\n    syslog {\n        user * {\n            any emergency;\n        }\n        file messages {\n            any notice;\n            authorization info;\n
       }\n        file interactive-commands {\n            interactive-commands any;\n        }\n    }\n}\ninterfaces {\n    em0 {\n        unit 0 {\n            family
 inet {\n                address 192.168.32.30/24;\n            }\n        }\n    }\n}\nsnmp {\n    community itential;\n    community redhat;\n}"
       },
 "strict_args": true
 }

Sample Response Object

{
        "role": "itential_restore_config",
        "task": "itential_restore_config response",
        "host": "junos_host",
        "status": "SUCCESS",
        "argument_warnings": null,
        "results": {
            "config_response": {
                "failed": false,
                "changed": true
            },
            "changed": false
        }
    }

Itential Automation Gateway

On this page:

Itential Roles

Execution Flow By Role Type

Fully Supported (Ansible-based)

Requirements

Example Host

Semi-Supported (Netmiko-based)

Requirements

Example Host (Explicit Usage)

Example Host (Implicit Usage)

Unsupported (Custom)

Requirements

Example Host

Role Execution Parameters

Task Key Naming Convention

Role Examples

`itential_cli`

`itential_get_info`

`itential_get_health`

`itential_get_config`

`itential_set_config`

`itential_restore_config`

Itential Automation Gateway

Help us improve by sending feedback...

On this page:

Itential Roles

Execution Flow By Role Type

Fully Supported (Ansible-based)

Requirements

Example Host

Semi-Supported (Netmiko-based)

Requirements

Example Host (Explicit Usage)

Example Host (Implicit Usage)

Unsupported (Custom)

Requirements

Example Host

Role Execution Parameters

Task Key Naming Convention

Role Examples

itential_cli

itential_get_info

itential_get_health

itential_get_config

itential_set_config

itential_restore_config

`itential_cli`

`itential_get_info`

`itential_get_health`

`itential_get_config`

`itential_set_config`

`itential_restore_config`